1、概要

1.1 文檔說明

本文檔主要提供給互億平臺(tái)的用戶對接接口的使用說明，開發(fā)者可以利用 ihuyi 提供的 HTTP 接口，調(diào)用 ihuyi 的短信驗(yàn)證碼/通知服務(wù)。

1.2 接口內(nèi)容

本文檔包含短信發(fā)送、余額查詢、發(fā)送回執(zhí)推送、上行回復(fù)推送等。

1.3 提交方式

GET / POST

1.4 加密方式

1、采用HTTPS協(xié)議提交請求
2、通過MD5動(dòng)態(tài)簽名方式加密

1.5 API ID / API KEY

登錄用戶中心，進(jìn)入【驗(yàn)證碼通知短信】模塊，在【產(chǎn)品總攬】頁面右上角，如下圖所示：

1.6 短信模版

短信模板是對您將要發(fā)送的短信進(jìn)行相似性提取后的內(nèi)容。舉個(gè)例子，

A 用戶在您平臺(tái)注冊會(huì)員，需要發(fā)送一條短信，內(nèi)容如下:

您好，您的驗(yàn)證碼是：666666

同時(shí)，B 用戶也在您的平臺(tái)注冊會(huì)員，發(fā)送了如下短信:

您好，您的驗(yàn)證碼是：888888

我們提取相似度以后，可以制作以下短信模板:

您好，您的驗(yàn)證碼是：【變量】

其中，變量是可變的，可以是 數(shù)字、字母、漢字。

注意:未付費(fèi)用戶僅可使用默認(rèn)短信模板（您的驗(yàn)證碼是：【變量】。請不要把驗(yàn)證碼泄露給其他人。），付費(fèi)用戶可以通過左側(cè)導(dǎo)航【驗(yàn)證碼通知短信】 -【短信發(fā)送】-【簽名/模版管理】新增短信模板，運(yùn)營商審核通過之后即可正式使用。

2、短信單條發(fā)送

2.1 接口描述

短信接口支持兩種提交方式，用戶可根據(jù)實(shí)際需求任選其一：

• 完整內(nèi)容方式（推薦）：直接傳遞完整的短信內(nèi)容進(jìn)行發(fā)送。
• 模板變量方式：使用預(yù)設(shè)模板，通過模板ID和變量實(shí)現(xiàn)短信發(fā)送，更便捷且更安全。

請求支持 POST 和 GET 兩種方法，數(shù)據(jù)格式統(tǒng)一為Content-Type: application/x-www-form-urlencoded ，字符編碼為 utf-8 ，支持全天24小時(shí)發(fā)送。

2.2 請求地址

https://106.ihuyi.com/webservice/sms.php?method=Submit

2.3 請求參數(shù)說明

參數(shù)名稱	參數(shù)值描述	必填
account	APIID（用戶中心【驗(yàn)證碼通知短信】-【產(chǎn)品縱覽】查看）	是
password	1、APIKEY（用戶中心【驗(yàn)證碼通知短信】-【產(chǎn)品縱覽】查看） 2、動(dòng)態(tài)密碼（生成方式見本文檔末尾說明）	是
mobile	接收短信的手機(jī)號(hào)碼，每次只能提交一個(gè)號(hào)碼	是
templateid	短信模板ID（使用模板變量方式發(fā)送時(shí)必填） 調(diào)試階段可使用系統(tǒng)默認(rèn)模板ID：1（模板內(nèi)容為：您的驗(yàn)證碼是：【變量】。請不要把驗(yàn)證碼泄露給其他人。）	否（使用模板變量方式時(shí)為必填）
content	根據(jù)發(fā)送方式不同： 1、完整內(nèi)容方式 提交完整的短信內(nèi)容，如：您的驗(yàn)證碼是：1234。請不要把驗(yàn)證碼泄露給其他人。 2、模板變量方式 模板中的變量內(nèi)容，多個(gè)變量以英文豎線（|）隔開 ①單變量示例 模板內(nèi)容：您的驗(yàn)證碼是：【變量】。請不要把驗(yàn)證碼泄露給其他人。 參數(shù)寫法：content=1234 最終短信為：您的驗(yàn)證碼是：1234。請不要把驗(yàn)證碼泄露給其他人。 ②多變量示例 模板內(nèi)容：訂單號(hào)：【變量1】，聯(lián)系人：【變量2】，手機(jī)號(hào)：【變量3】，金額：【變量4】。 參數(shù)寫法：content=20180515006|張三|136xxxxxxxx|100元 最終短信為：訂單號(hào)：20180515006，聯(lián)系人：張三，手機(jī)號(hào)：136xxxxxxxx，金額：100元。 支持500字以內(nèi)的長短信，長短信按多條計(jì)費(fèi)	是
time	Unix時(shí)間戳（10位整型數(shù)字，使用動(dòng)態(tài)密碼方式時(shí)必填）	否
format	返回?cái)?shù)據(jù)格式（可選值：xml 或 json，默認(rèn)xml）	否

2.5 響應(yīng)參數(shù)

code	msg
0	提交失敗
2	提交成功
400	非法ip訪問
401	帳號(hào)不能為空
402	密碼不能為空
403	手機(jī)號(hào)碼不能為空
4030	手機(jī)號(hào)碼已被列入黑名單
404	短信內(nèi)容不能為空
405	API ID 或 API KEY 不正確
4050	賬號(hào)被凍結(jié)
40501	動(dòng)態(tài)密碼已過期
40502	動(dòng)態(tài)密碼校驗(yàn)失敗
40504	超出每天最大發(fā)送量
40505	沒有簽定合同
4051	剩余條數(shù)不足
4052	訪問 ip 與備案 ip 不符
4053	用戶不存在
4054	帳戶無效
406	手機(jī)格式不正確
407	短信內(nèi)容含有敏感字符
4070	簽名格式不正確
4071	沒有提交備案模板
4072	提交的短信內(nèi)容與審核通過的模板內(nèi)容不匹配
40722	變量內(nèi)容超過指定的長度【8】
4073	短信內(nèi)容超出長度限制
4074	短信內(nèi)容包含 emoji 符號(hào)
4075	簽名未通過審核
4077	短信變量內(nèi)容含有敏感字符
408	發(fā)送超限【50】條，已加入黑名單，可登入平臺(tái)解除
4082	超出同一手機(jī)號(hào)一天之內(nèi)【100】條短信限制
4085	同一手機(jī)號(hào)一天之內(nèi)驗(yàn)證碼短信發(fā)送超出【10】條

2.6 請求示例

（1）完整內(nèi)容方式示例（推薦）：

https://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手機(jī)號(hào)碼&content=您的驗(yàn)證碼是：1234。請不要把驗(yàn)證碼泄露給其他人。

（2）模板變量方式示例：

https://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手機(jī)號(hào)碼&templateid=1&content=1234

示例中使用默認(rèn)模板（ID=1），內(nèi)容為：“您的驗(yàn)證碼是：【變量】。請不要把驗(yàn)證碼泄露給其他人。”
如使用自定義模板，模板含多個(gè)變量時(shí)，content需以豎線 | 隔開，如下所示：

https://106.ihuyi.com/webservice/sms.php?method=Submit&account=APIID&password=APIKEY&mobile=手機(jī)號(hào)碼&templateid=144219&content=20180515006|張三|136xxxxxxxx|100元

請注意模板中變量與傳入?yún)?shù)必須一一對應(yīng)。

3、短信批量發(fā)送

3.1 接口描述

通過POST方式進(jìn)行短信提交，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded，數(shù)據(jù)編碼采用utf-8格式，24小時(shí)全天發(fā)送。

3.2 請求地址

https://106.ihuyi.com/webservice/sms.php?method=SubmitBatch

3.3 請求參數(shù)

參數(shù)名稱	參數(shù)值描述	必填
account	APIID(用戶中心【驗(yàn)證碼通知短信】-【產(chǎn)品總覽】查看)	是
password	1、APIKEY(用戶中心【驗(yàn)證碼通知短信】-【產(chǎn)品總覽】查看) 2、動(dòng)態(tài)密碼(生成動(dòng)態(tài)密碼方式請看該文檔末尾的說明)	是
mobile	手機(jī)號(hào)碼（可參考下文示例）	是
templateid	模板ID	選填
content	短信內(nèi)容	選填
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否
format	返回格式（可選值為：xml或json，系統(tǒng)默認(rèn)為xml）	否
sendTime	定時(shí)發(fā)送時(shí)間	否

用戶通過http 或 https提交發(fā)送短信請求到服務(wù)器后，服務(wù)器會(huì)返回一串xml格式的字符串，SubmitBatchResult結(jié)構(gòu)說明如下：

參數(shù)名稱	類型	描述
code	int	返回值為2時(shí)，表示提交成功
batchid	string	流水號(hào)（對應(yīng)提交時(shí)返回的batchid）
msg	string	回執(zhí)狀態(tài)說明

3.4 響應(yīng)參數(shù)

code	msg
0	提交失敗
2	提交成功
400	非法ip訪問
401	帳號(hào)不能為空
402	密碼不能為空
403	手機(jī)號(hào)碼不能為空
4031	手機(jī)號(hào)碼必須大于1個(gè)
4032	手機(jī)號(hào)碼必須小于5000個(gè)
404	模板ID模和模板內(nèi)容二選一
4041	模板ID不正確
405	API ID 或 API KEY 不正確
4050	賬號(hào)被凍結(jié)
40501	動(dòng)態(tài)密碼已過期
40502	動(dòng)態(tài)密碼校驗(yàn)失敗
40505	沒有簽定合同
4051	剩余條數(shù)不足
4052	訪問 ip 與備案 ip 不符
4053	用戶不存在
4054	帳戶無效
406	手機(jī)格式不正確
407	短信內(nèi)容含有敏感字符
4070	簽名格式不正確
4074	短信內(nèi)容包含 emoji 符號(hào)
4075	簽名未通過審核
4077	短信變量內(nèi)容含有敏感字符
408	定時(shí)發(fā)送時(shí)間無效(大于當(dāng)時(shí)間10分鐘，小于當(dāng)前時(shí)間7天
409	計(jì)費(fèi)錯(cuò)誤

3.5 傳參說明

1、不含變量
手機(jī)號(hào)格式： 號(hào)碼之間使用英文逗號(hào)隔開，如：136xxxx1111,136xxxx2222,136xxxx3333
模板ID： 對應(yīng)您在平臺(tái)報(bào)備過的模板ID，如：624452
模板內(nèi)容：您有新的訂單，請注意查收。

2、含變量
手機(jī)號(hào)格式： 變量之間用半|符號(hào)隔開，如：136xxxx1111|11111111|菜鳥,136xxxx2222|22222222|京東,136xxxx3333|3333333333|順豐
模板ID： 對應(yīng)您在平臺(tái)報(bào)備過的模板ID，如：624452
模板內(nèi)容：您的訂單號(hào)是：【變量】。已由【變量】快遞發(fā)出，請注意查收。

注意：
單次提交最少2個(gè)號(hào)碼，最多5000個(gè)號(hào)碼
模板ID和模板內(nèi)容二選一，如果傳模板內(nèi)容或者號(hào)碼數(shù)量超過500都會(huì)進(jìn)入人工審核流程。

4、余額查詢

4.1 接口描述

通過POST、 GET 方式查詢你的賬戶驗(yàn)證碼通知短信剩余條數(shù)，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded，數(shù)據(jù)編碼采用utf-8格式。

4.2 請求地址

http://106.ihuyi.com/webservice/sms.php?method=GetNum

4.3 請求參數(shù)

參數(shù)名稱	參數(shù)值描述	是否必填
account	APIID（請登錄用戶中心【驗(yàn)證碼通知短信】-【產(chǎn)品總覽】查看）	是
password	1、APIKEY（請登錄用戶中心【驗(yàn)證碼通知短信】-【產(chǎn)品總覽】查看） 2、動(dòng)態(tài)密碼（生成動(dòng)態(tài)密碼方式請看該文檔末尾的說明）	是
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否
format	返回格式（可選值為：xml或json，系統(tǒng)默認(rèn)為xml）	否

用戶通過http 或 https提交帳戶余額查詢請求到服務(wù)器后，服務(wù)器會(huì)返回一串xml格式的字符串，GetNumResult結(jié)構(gòu)說明如下：

參數(shù)名稱	類型	描述
code	int	狀態(tài)返回值
msg	string	查詢結(jié)果描述
num	string	剩余數(shù)量

4.4 響應(yīng)示例

示例（成功）

2 查詢成功 856

示例（失?。?/p>

405 account或password不正確0

4.5 響應(yīng)參數(shù)

code	msg
2	查詢成功
400	非法ip訪問
401	帳號(hào)不能為空
402	密碼不能為空
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)

4.6 GET請求示例

http://106.ihuyi.com/webservice/sms.php?method=GetNum&account=APIID&password=APIKEY

5、發(fā)送回執(zhí)推送

5.1 接口描述

用戶先提供數(shù)據(jù)接收地址，然后綁定到互億無線系統(tǒng)后臺(tái)，平臺(tái)會(huì)以POST方式實(shí)時(shí)的將回執(zhí)信息推送到此地址，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded。

5.2 推送參數(shù)

參數(shù)名稱	參數(shù)值描述
code	狀態(tài)值（2成功 其他為失?。?/td>
msg	回執(zhí)狀態(tài)說明
mobilephone	手機(jī)號(hào)碼
smsid	單條發(fā)送流水號(hào)（對應(yīng)提交時(shí)返回的smsid）
batchid	批量發(fā)送流水號(hào)（對應(yīng)提交時(shí)返回的batchid）
report_time	回執(zhí)時(shí)間 例:2017-08-02 14:31:51

注意:
1、如多條批量發(fā)送，則會(huì)額外返回batchid。
2、成功接收請輸出字符 “success” (不包含引號(hào))結(jié)束推送，否則以接收失敗處理。 每個(gè)回執(zhí)最多推送 3 次。每次間隔疊加 60 秒。

6、上行回復(fù)推送

6.1 接口描述

用戶先提供數(shù)據(jù)接收地址，然后綁定到互億無線系統(tǒng)后臺(tái)，平臺(tái)會(huì)以 POST 方式實(shí)時(shí)的將 回復(fù)信息推送到此地址。

6.2 推送參數(shù)

參數(shù)名稱	參數(shù)值描述
mobilephone	手機(jī)號(hào)碼
content	上行內(nèi)容
smsid	流水號(hào)(對應(yīng)提交時(shí)返回的 smsid)(僅作參考)
batchid	批量發(fā)送流水號(hào)（對應(yīng)提交時(shí)返回的batchid）
reply_time	上行時(shí)間 例:2017-05-24 17:46:50

注意:
1、如多條批量發(fā)送，則會(huì)額外返回batchid。
2、成功接收請輸出字符 “success” (不包含引號(hào))結(jié)束推送，否則以接收失敗處理。每個(gè)回執(zhí)最多推送 3 次。每次間隔疊加 60 秒。

7、提交模板

7.1 接口描述

通過 POST、 GET 方式提交短信模版，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded，數(shù)據(jù)編碼采用 utf-8 格式。

7.2 請求地址

http://106.ihuyi.com/webservice/sms.php?method=AddTemplate&account=APIID&password=APIKEY&content=您的驗(yàn)證碼是：【變量】。請不要把驗(yàn)證碼泄露給其他人。

7.3 請求參數(shù)

參數(shù)名稱	參數(shù)值描述
method	AddTemplate
account	提交賬戶
password	提交賬戶密碼 (可以明文密碼或使用 32 位 MD5 加密)
content	模板內(nèi)容
content2	實(shí)際發(fā)送的內(nèi)容（示例）
type	1驗(yàn)證碼 2通知
scene	使用場景

返回值 AddTemplateResult 結(jié)構(gòu)說明:

參數(shù)名稱	類型	描述
code	int	返回值為 2 時(shí)，表示添加成功
msg	string	提交狀態(tài)描述
templateid	int	添加成功則返回模板 ID

7.4 響應(yīng)參數(shù)

code	msg
2	添加成功
400	非法ip訪問
401	用戶名不能為空
402	密碼不能為空
404	模板內(nèi)容不能為空
4041	模板內(nèi)容長度不符合（15-500個(gè)字符）
4042	使用場景長度為50個(gè)字符以內(nèi)
4043	實(shí)際發(fā)送的內(nèi)容（示例）不能為空
4044	實(shí)際發(fā)送的內(nèi)容（示例）長度不符合（15-500個(gè)字符）
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)
406	未充值不能提交模板
4066	添加太頻繁，支持1分鐘10次請求
407	模板內(nèi)容含有敏感字符
408	模板己存在

7.5 模板審核狀態(tài)推送

在遵守 HTTP 協(xié)議規(guī)范的前提下，通過 POST 方式將回執(zhí)推送到用戶指定的 URL 地址。

參數(shù)說明:

參數(shù)名稱	參數(shù)值描述
code	狀態(tài)值(2 成功 0 駁回)
msg	審核狀態(tài)描述
templateid	模板 ID

注意:

1.成功接收請輸出字符 “success” (不包含引號(hào))結(jié)束推送，否則以接收失敗處理。

2.每個(gè)回執(zhí)最多推送 3 次。每次間隔疊加 60 秒。

3.code 值說明

2 成功

0 駁回(原因請看 msg 字段)

8、刪除模板

8.1 接口描述

通過POST、 GET 方式提交短信模版，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded，數(shù)據(jù)編碼采用utf-8格式。

8.2 請求地址

http://106.ihuyi.com/webservice/sms.php?method=DelTemplate&account=APIID&password=APIKEY&templateid=123 

8.3 請求參數(shù)

參數(shù)名稱	參數(shù)值描述
method	DelTemplate
account	提交賬戶
password	提交賬戶密碼 (可以明文密碼或使用 32 位 MD5 加密)
templateid	模板id

返回值 AddTemplateResult 結(jié)構(gòu)說明:

參數(shù)名稱	類型	描述
code	int	返回值為 2 時(shí)，表示刪除成功
msg	string	提交狀態(tài)描述

8.4 響應(yīng)參數(shù)

code	msg
2	刪除成功
400	非法ip訪問
401	用戶名不能為空
402	密碼不能為空
404	模板ID不能為空或模板ID不存在
405	用戶名或密碼不正確
4050	賬號(hào)被凍結(jié)

9、生成動(dòng)態(tài)密碼方式

以PHP為例，提交短信驗(yàn)證碼的生成方式：

$time = time();
$password = md5($account.$apikey.$mobile.$content.$time);

例如：

APIID： test
APIKEY：1q784322ba1d9bb88d50cf5cdfd89k7d
手機(jī)號(hào)：138xxxxxxxx
內(nèi)容：您的驗(yàn)證碼是：2546。請不要把驗(yàn)證碼泄露給其他人。
time：1451544941
結(jié)果：$password=md5("test1q784322ba1d9bb88d50cf5cdfd89k7d138xxxxxxxx 您的 驗(yàn)證碼是:2546。請不要把驗(yàn)證碼泄露給其他人。1451544941");

注意:因?yàn)槎绦艃?nèi)容會(huì)包含中文，所以字符編碼統(tǒng)一為 UTF-8

查詢剩余條數(shù)的生成方式：

$time = time();
$password = md5($account.$apikey.$time);

例如：

APIID： test
APIKEY：1q784322ba1d9bb88d50cf5cdfd89k7d
手機(jī)號(hào)：138xxxxxxxx
time：1451544941
結(jié)果：$password=md5("test1q784322ba1d9bb88d50cf5cdfd89k7d1451544941");

Unix時(shí)間戳參考地址：http://tool.chinaz.com/Tools/unixtime.aspx

10、常見問題

10.1 如何處理亂碼

說明: 將短信內(nèi)容( content)進(jìn)行 UTF-8 編碼后提交。

PHP 亂碼:

$content = iconv("GBK","UTF-8",$content);

JAVA 亂碼:

sb.append("&content="+URLEncoder.encode(content,"UTF-8"));

C#亂碼:

byte[] bTemp = System.Text.Encoding.GetEncoding("GBK").GetBytes(sbTemp.ToString());

10.2 如何實(shí)現(xiàn) UNIX 時(shí)間戳

語言	代碼
JAVA	String date = new java.text.SimpleDateFormat("dd/MM/yyyy HH:mm:ss").format(new java.util.Date(Unix timestamp *1000))
Linux	date -d @Unix timestamp
C	strptime(datetime, "%Y-%m-%d %H:%M:%S", &tm_time); unixtime = mktime(&tm_time);
C++	std::time_t t = std::time(0);
DELPHI	uses DateUtils; DateTimeToUnix(Now)
GO	import "time" cur := time.Now() timestamp := cur.UnixNano() / 1000000
Perl	先 my $time = Unix timestamp 然后 my ($sec, $min, $hour, $day, $month, $year) = (localtime($time))[0,1,2,3,4,5,6]
PHP	date("r", Unix timestamp)
Node.js	var date = new Date( time * 1000 ); var time = date.getTime()/1000;
Python	先 import time 然后 time.gmtime(Unix timestamp)
Ruby	Time.at(Unix timestamp)
SHELL	date +%s //UNIX 的時(shí)間戳;
VBScript / ASP	DateAdd("s", Unix timestamp, "01/01/1970 00:00:00")
VB6	DateDiff("s", "1970-1-1 0:0:0", ToUnixTime)
易語言	時(shí)間_到時(shí)間戳()

11、短信 DEMO

互億無線提供各種語言的短信接口DEMO，詳情請點(diǎn)擊：短信驗(yàn)證碼/通知短信接口示例

12、短信插件

互億無線提供近百種主流系統(tǒng)的短信插件，能幫助你快速接入驗(yàn)證碼短信，詳情請點(diǎn)擊：短信驗(yàn)證碼插件

13、驗(yàn)證碼通知短信常見問題

提供驗(yàn)證碼通知短信接入、使用中的常見問題，請點(diǎn)擊瀏覽

14、驗(yàn)證碼/通知短信接口產(chǎn)品開通

自助開通驗(yàn)證碼/通知短信接口
開通即贈(zèng)免費(fèi)試用短信，免費(fèi)試用不限時(shí)長
短信套餐報(bào)價(jià) 免費(fèi)開通試用賬戶 驗(yàn)證碼通知短信產(chǎn)品介紹